3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Manipulating Matrix Transforms

QuickDraw 3D provides routines that you can use to create and manipulate matrix transforms.

Q3MatrixTransform_New

You can use the Q3MatrixTransform_New function to create a new matrix transform.



 
TQ3TransformObject Q3MatrixTransform_New (

                     const TQ3Matrix4x4 *matrix);

matrix: On entry, a pointer to a 4-by-4 matrix that defines the desired new transform.

DESCRIPTION

The Q3MatrixTransform_New function returns, as its function result, a reference to a new transform object of type kQ3TransformTypeMatrix using the data passed in the matrix parameter. The data you pass in the matrix parameter is copied into internal QuickDraw 3D data structures. If QuickDraw 3D cannot allocate memory for those structures, Q3MatrixTransform_New returns the value NULL .

It is your responsibility to ensure that the matrix specified by the matrix parameter is affine and invertible. QuickDraw 3D does not check for these qualities.

Q3MatrixTransform_Submit

You can use the Q3MatrixTransform_Submit function to submit a matrix transform without creating an object or allocating memory.



 
TQ3Status Q3MatrixTransform_Submit (

                     const TQ3Matrix4x4 *matrix, 

                     TQ3ViewObject view);

matrix: A pointer to a 4-by-4 matrix.
view: A view.

DESCRIPTION

The Q3MatrixTransform_Submit function pushes the matrix transform specified by the matrix parameter on the view transform stack of the view specified by the view parameter. The function returns kQ3Success if the operation succeeds and kQ3Failure otherwise.

SPECIAL CONSIDERATIONS

You should call this function only in a submitting loop.

Q3MatrixTransform_Get

You can use the Q3MatrixTransform_Get function to query the private data stored in a matrix transform.



 
TQ3Status Q3MatrixTransform_Get (

                     TQ3TransformObject transform, 

                     TQ3Matrix4x4 *matrix);

transform: A transform.
matrix: On exit, a pointer to the matrix associated with the transform specified in the transform parameter.

DESCRIPTION

The Q3MatrixTransform_Get function returns, in the matrix parameter, information about the matrix transform specified by the transform parameter. You should use Q3MatrixTransform_Get only with transforms of type kQ3TransformTypeMatrix .

Q3MatrixTransform_Set

You can use the Q3MatrixTransform_Set function to set new private data for a matrix transform.



 
TQ3Status Q3MatrixTransform_Set (

                     TQ3TransformObject transform, 

                     const TQ3Matrix4x4 *matrix);

transform: A transform.
matrix: A pointer to the new matrix to be associated with the transform specified in the transform parameter.

DESCRIPTION

The Q3MatrixTransform_Set function sets the matrix transform specified by the transform parameter to the matrix passed in the matrix parameter. You should use Q3MatrixTransform_Set only with transforms of type kQ3TransformTypeMatrix .